RISCOS Library

The riscos library provides values

     version, sys, dim, !, ?, $, dir, filetype, block

The number version has the value 100 times the RiscLua version number, for versions higher than 5.00, and nil otherwise.

The function sys behaves much like SYS in Basic. It provides the means for RiscLua to call SWIs {SoftWare Interrupts).

      out0, out1, ... = sys (swi, in0, in1, ...)
The first argument is the SWI number or name. The subsequent arguments are the register values on entry. A nil value indicates that the register value on exit from the previous SWI call should be used. If a string value is passed then the string is stored in a temporary array whose address is used for the argument of the SWI. The return values are the register values on exit from the SWI, if the call succeeded without error. In case of error, the returned values are nil followed by an error message.

RISC OS uses arrays to pass data in and out of SWIs if there are more data than registers. The function dim takes a number (giving how many bytes) or a string as argument and it allocates a garbage-collectible array in memory. It returns the address of the start of the array, which is always a multiple of 4. When the argument is a string enough bytes are reserved to store the string, and the string is stored in the array with no terminating zero byte. At the same time, as a side-effect, it creates a userdatum block[x] where x is the address returned. The expression #block[x] evaluates to the number of bytes allocated at x, which is convenient for checking bounds. The array will not be garbage-collected while block[x] is non-nil.

The riscos library provides three rather strange tables: !, ? and $. These can be used like the indirection operators of Basic. The values of these tables at a numeric index (which must be a multiple of 4 for !) give the word, byte or zero-terminated string at that address in memory. They can be assigned to as well as read. So what in Basic might be:

    DIM x% 15
    ?x% = 0
    x%!4 = 15
    $(x%+8) = "abc"
    ......

could be written in RiscLua as:

   local !,?,$,dim in riscos
   local x = dim(16)
   ?[x] = 0
   ![x+4] = 15
   $[x+8] = "abc"
   ..........
Note that the argument of dim determines the total number of bytes, whereas in Basic the number is the highest offset, i.e. one less.

The expression $[b] gives the zero-terminated string at address b. The expression $(b) gives the control-character-terminated string at address b, and $(b,n) the string of length n at address b. However, the assignment

            $[b] = s
stores the string s at b whatever control characters s contains.

The directory iterator dir used with the syntax:

   for leafname, ftype in dir (dirname) do
     ................
   end
The function filetype takes the pathname of a filer object as argument and returns nil if the object does not exist and the numeric value of its filetype if it does.

It is up to the programmer to ensure that his or her code is safe. In some ways, providing these more Basic-like facilities rather goes against the security-conscious grain of Lua.